home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / mus / misc / xmodule30.lha / XModule / XModule.doc < prev    next >
Text File  |  1995-02-05  |  36KB  |  904 lines
  1.  
  2.  
  3.    This manual documents XModule version 3.0 released on 06 Jan 95.
  4.  
  5.    Copyright (C) 1993-1995 by Bernardo Innocenti, Freely distributable,
  6. all rights reserved.
  7.  
  8. Overview
  9. ********
  10.  
  11.    The Amiga computer has standard file formats for almost everything.
  12. Graphics, text, animation, hypertext and many other data types are
  13. easily imported into any program that supports the given standards, but
  14. this isn't true for music.  Too bad the music interchange file format
  15. defined by Electronic Arts (the old IFF SMUS) was too poor to be usable
  16. in high-quality music sequencers.  Therefore, every music editor
  17. created its own proprietary module format, so that, for instance, you
  18. cannot load into ProTracker music written with Oktalyzer.
  19.  
  20.        XModule (pronounced Cross Module) born as music module
  21. conversion utility that tries to solve this problem.  The project
  22. started in early 1993, as a friend of mine (Fabio), who wrote a lot of
  23. (good) music on Oktalyzer, needed ProTracker to obtain certain effects.
  24. He had an old PD conversion program called Tracker that worked only
  25. in particular conditions and was really bogus.  So I decided to contact
  26. the author and he let me have the source for Lit30000  (about $20).
  27.  
  28.    The original program has been completely rewritten from scratch, as
  29. the source was poorly coded.  Now XModule sports many other features,
  30. like module optimization, a nice user interface and complex module
  31. editing functions.
  32.  
  33.    This is why I like to call XModule a module processor. XModule is
  34. to music processing what ADPro and ImageFX are to image processing (I
  35. am not very modest :-).
  36.  
  37. Distribution
  38. ************
  39.  
  40.    XModule is a Freeware program.  This means that you (probably)
  41. have got it free and you should not ask any money if you decide to
  42. copy it for someone else.  If, instead, someone sold you XModule for a
  43. price higher than the media used to store it on (i.e. $1 for a DD
  44. disk), tell him he should try making money honestly.
  45.  
  46.    I'm not asking you to pay for XModule because I never paid for a
  47. ShareWare program, so I felt that I somehow had to pay my debt and I
  48. decided to distribute XModule as free software, a little gift to all
  49. the Amiga community.  Feel free to distribute XModule to your friends
  50. and enemies, but, if you do so, you must keep the documentation and
  51. the other distribution files together with the executable.  The source
  52. code is not required, but I'm distributing it to let others take
  53. advantage of my work, so, if possible, try to include the source too.
  54.  
  55.    Fred Fish, SAN, ADS and Aminet are especially granted permission to
  56. include XModule into their PD libraries.  Other PD libraries are
  57. welcome as well.
  58.  
  59.    If you intend to include XModule or parts of it in a commercial
  60. package, please at least send me a free copy of the product.  I would
  61. be honored to see one of my programs being part of a commercial package.
  62.  
  63.    You can modify or improve XModule (see Programmers), only be so kind
  64. to return the new source code to me, so I can put the new features in
  65. the next release.  And, please, do not strip my name from the
  66. documentation, the program source, or the executable.
  67.  
  68.    This product is provided as is, without warranties of any kind:
  69. the author of this program cannot be held liable for any defects in the
  70. executable nor in the documentation or in any other files contained in
  71. this package.  Any damage directly or indirectly caused by the
  72. use/misuse of XModule is the sole responsibility of the user her/him
  73. self.  In other words: XModule never formatted my hard disk nor killed
  74. my dog, so I suppose it won't cause any damage to your system either,
  75. but, just in case, do not blame me if something nasty happens.
  76.  
  77. Getting Started
  78. ***************
  79.  
  80.    XModule requires Kickstart version 2.0 or greater.  The reason is
  81. that I hate programming on 1.3 and I won't do it any more.  If you still
  82. haven't upgraded to 2.0, you'll miss the chance to run XModule and many
  83. other wonderful programs.  So what are you waiting for?
  84.  
  85.    XModule also takes advantage of some 2.1 and 3.0 features, such as
  86. DataTypes, AmigaGuide, Locale and many enhancements for the user
  87. interface.
  88.  
  89.    You can invoke XModule either from the Shell or Workbench.  XModule
  90. accepts both command line and ToolTypes arguments.  Workbench and Shell
  91. parameters are the same.  The full AmigaDOS template is:
  92.  
  93.      XModule FROM/M,PUBSCREEN/K,PORTNAME/K,SETTINGS/K,
  94.       CX_POPUP/T,CX_POPKEY/K,CX_PRIORITY/K/N,
  95.       ICONXPOS/K/N,ICONYPOS/K/N,ICONNAME/K
  96.  
  97. The FROM keyword specifies modules to load at startup time.  Standard
  98. AmigaDOS wildcards can be used to match more than one module.  From
  99. Workbench, you multi-select module icons instead of specifying a
  100. ToolType.
  101.  
  102.    Specifying the PUBSCREEN keyword, followed by a public screen name,
  103. allows you to open XModule on an existing public screen.  The given
  104. name should match exactly (case matters), or the system won't be able to
  105. find the requested screen.  If the requested screen does not exist, a
  106. new public screen will be opened, cloning the resolution and colors of
  107. the default public screen (usually the Workbench screen).  Specifying
  108. an empty string (eg.: "") you will automatically pick the default
  109. public screen.  Note that this behavior is not standard: most
  110. commodities will abort if the requested public screen does not exist.
  111. The default is to use or create a public screen called XModule.
  112.  
  113.        PORTNAME will change the name of XModule's ARexx port.  If a
  114. port with this name already exists, a number (eg: .1) will be
  115. appended to the name, until a unique name is found.  You can disable
  116. the ARexx port providing an empty string (eg.: "") for PORTNAME.
  117. The port name defaults to XMODULE.  For more information about the
  118. ARexx port, consult the ARexx Interface chapter.
  119.  
  120.        SETTINGS causes XModule to use the given settings file instead
  121. of looking for the default preferences file.
  122.  
  123.        CX_POPUP controls wether the user interface should show as
  124. soon as XModule starts.  The default is to always show the interface.
  125. When used from the shell, CX_POPUP acts as a toggle, turning off the
  126. user interface.  From Workbench, you specify CX_POPUP=YES or
  127. CX_POPUP=NO to show and hide the user interface, respectively.
  128. See Commodities.
  129.  
  130.        CX_POPKEY specifies the hotkey that pops up XModule's user
  131. interface.  The given string should be a valid Commodities input
  132. description.  You can disable XModule's Commodities broker specifying
  133. an empty string (eg.: "") for CX_POPUP.  The default is ctrl alt
  134. x.  See Commodities.
  135.  
  136.        CX_PRIORITY sets the Commodities priority for the XModule
  137. broker.  An high priority causes the input to be processed by {No Value
  138. For "prgnmae"} before other commodities with a lower priority. The
  139. priority ranges from +127 to -128.  The default priority is 0.  See
  140. Commodities.
  141.  
  142.        ICONXPOS specifies the X position of XModule's AppIcon.  The
  143. default is to let Workbench choose a suitable position for the icon.
  144.  
  145.        ICONYPOS specifies the Y position of XModule's AppIcon.  The
  146. default is to let Workbench choose a suitable position for the icon.
  147.  
  148.        ICONNAME specifies the name of XModule's AppIcon.  The default
  149. name is XModule.
  150.  
  151. User Interface
  152. **************
  153.  
  154.    XModule's GUI follows Commodore's 2.0 style guidelines.  Under
  155. Kickstart 3.0 and above, XModule takes advantage of new OS capabilities
  156. to enhance some aspects of the GUI.
  157.  
  158. Windows Layout
  159. ==============
  160.  
  161.    Gadget and menu layout is font sensitive, but using some fancy fonts
  162. could result in a somewhat weird look.  If you are using a very big
  163. font and a window becomes too big to fit in the screen, topaz/8 will
  164. be used as a fallback for rendering that window.
  165.  
  166.    When you close a window, it will remember its position and size when
  167. you open it again.  The same is true for window zooming.
  168.  
  169. Shortcut Keys
  170. =============
  171.  
  172.    In all windows, the following shortcut keys are active:
  173.  
  174. ESC
  175.      Close the active window.  Does not work with ToolBox window, as it
  176.      would make it too easy to accidentally exit the program.
  177.  
  178. HELP
  179.      Bring up AmigaGuide on-line help.  See On-Line Help.
  180.  
  181. TAB
  182.      Cycle forward through string and numeric gadgets within the active
  183.      window.  SHIFT-TAB will cycle backwards.  TAB also activates
  184.      the first string or numeric gadget if none is selected.
  185.  
  186. RETURN
  187.      Activate the first string or numeric gadget in the active window.
  188.  
  189. Cursor UP/DOWN
  190.      Move up and down in a viewlist whenever the active window contains
  191.      one.  SHIFT-Cursor moves 5 items up/down. ALT-Cursor moves to
  192.      the top or to the bottom of the list.  This shortcut requires at
  193.      least Kickstart 3.0.
  194.  
  195.    In addition, gadgets with underscored characters in labels, can be
  196. operated hitting the highlighted key.  SHIFT-key acts the opposite of
  197. the unshifted key (sliders are decremented by one, cycle gadgets will
  198. cycle backwards, etc).  Keyboard shortcuts will not work for all gadget
  199. kinds under Kickstart 2.0.
  200.  
  201. On-Line Help
  202. ============
  203.  
  204.    This feature requires amigaguide.library, which is distributed
  205. with Workbench version 2.1 and up, and XModule.guide located in the
  206. current directory or in the same directory of XModule's executable or
  207. in the HELP:language/ directory, where language is any of your
  208. Locale preferred languages.  AmigaGuide(TM) is also available as a
  209. freely distributable package for 1.3-2.0 users.
  210.  
  211.    To get help on a gadget, press HELP while the mouse pointer is over
  212. the gadget.  To get help on a string gadget, activate it and press
  213. HELP.  Hitting HELP while the mouse isn't over a gadget, will give you
  214. help on the active window.
  215.  
  216.    To get help on a menu item, hilight the item and press HELP while
  217. keeping the right mouse button pressed.
  218.  
  219. Localization
  220. ============
  221.  
  222.    Localization requires locale.library,  which is distributed with
  223. Workbench version 2.1 and up, and the catalog file XModule.catalog
  224. located in the same directory of XModule's executable or in the
  225. LOCALE:catalogs/language/ directory, where langage is is any of
  226. your Locale preferred languages.
  227.  
  228. Commodities support
  229. ===================
  230.  
  231.    XModule is a Commodity and can be controlled by the Commodities
  232. Exchange program.
  233.  
  234.    XModule will pop up when its hotkey is typed; the main window will
  235. activate and the screen will move to the front.  If XModule's interface
  236. is hidden, it will be revealed.
  237.  
  238.    The user interface can be hidden with the Exchange program.  When
  239. the user interface is hidden, the only ways you have to still operate
  240. XModule is through the ARexx port or the AppIcon.
  241.  
  242.    You can also control XModule by sending the following signals to its
  243. process:
  244.  
  245. *CTRL-C
  246.      Quit XModule.
  247.  
  248. *CTRL-D
  249.      Disable the Commodities broker (equivalent to selecting
  250.      Inactive with Commodities Exchange).
  251.  
  252. *CTRL-E
  253.      Enable the Commodities broker (equivalent to selecting Active
  254.      with Commodities Exchange).
  255.  
  256. *CTRL-F
  257.      Deiconify XModule (equivalent to double-clicking on the AppIcon).
  258.  
  259. Default Icons
  260. =============
  261.  
  262.    When XModule creates an icon for a file, it looks for the user
  263. preferred icon for the type of data being saved.
  264.  
  265.    The template icons can be placed in the same drawer where XModule
  266. resides or in the ENV:sys/ directory.  In the latter case, you should
  267. store them in ENVARC:sys/ to have them copied to ENV:sys/ every
  268. time the system boots up.
  269.  
  270.    Template icons should be only of type Project.  When XModule does
  271. not find the template icon, it uses the default Project icon instead.
  272.  
  273.    Whenever the default icon does not have its own default tool, it
  274. will be set to XModule's executable.
  275.  
  276.    The following default icons are supported:
  277.  
  278. -def_Module
  279. -def_Instrument
  280. Panels
  281. ******
  282.  
  283.    Sorry, XModule's documentation is still incomplete.  The next release
  284. will hopefully be more accurate.
  285.  
  286.    But wait! Do not commit suicide for this reason: XModule is very
  287. easy to use, and you will be able to operate it even without this
  288. chapter.
  289.  
  290. ToolBox Window
  291. ==============
  292.  
  293. Gadgets
  294. -------
  295.  
  296. Patterns (P)
  297.      This option has not been implemented yet.
  298.  
  299. Instruments (I)
  300.      Opens or activates the Instruments information window.
  301.  
  302. Sequence (Q)
  303.      Opens or activates the Sequence editor.
  304.  
  305. Songs (S)
  306.      Opens or activates the Song information window.
  307.  
  308. Optimization (O)
  309.      Opens or activates the Optimization window.
  310.  
  311. Play (P)
  312.      This option has not been implemented yet.
  313.  
  314. Project Menu
  315. ------------
  316.  
  317. New (Amiga-N)
  318.      Creates an empty song.
  319.  
  320. Open (Amiga-O)
  321.      Opens a module over the current one.
  322.  
  323. Save (Amiga-S)
  324.      Saves the current song to the same path it was loaded from.
  325.  
  326. Save As (Amiga-A)
  327.      Opens a file requester and saves the current song to the selected
  328.      path.
  329.  
  330. Clear Module (Amiga-C)
  331.      Opens or activates the Clear Module panel.
  332.  
  333. Join Modules (Amiga-J)
  334.      This option has not been implemented yet.
  335.  
  336. About (Amiga-?)
  337.      Brings up a requester showing various information on XModule.
  338.  
  339. Iconify (Amiga-I)
  340.      Closes all open windows and screens and puts an AppIcon on the
  341.      Workbench.  You can De-Iconify XModule by double clicking on the
  342.      icon.
  343.  
  344. Quit (Amiga-Q)
  345.      Quits XModule.
  346.  
  347. Format Conversion
  348. *****************
  349.  
  350.    XModule can load and save modules created by other music editors.
  351. The following is a list of all supported module formats:
  352.  
  353.    As a matter of fact, there are things that simply cannot be done
  354. because of the big differences between different module formats.  Below
  355. is a list of the internal limitations of each module format.  When you
  356. save to a particular format and the module exceeds one of these values,
  357. or makes use of features not implemented, some data will be stripped
  358. away to produce at least a partial conversion.
  359.  
  360.  
  361.      Program          Instr  MaxPatt PattLen SongLen InstrLen Tracks
  362.      ---------------------------------------------------------------
  363.      Oktalyzer         36      128     128     128     128K     4
  364.      Sound Tracker     15       64      64     128      64K     4
  365.      Noise Tracker     31       64      64     128      64K     4
  366.      StarTrekker       31       64      64     128      64K    4/8
  367.      Pro Tracker       31      100      64     128      64K     4
  368.      MED/OctaMED       63      256     256     256   No Limit  1-64
  369.      
  370.      Where:
  371.      #Instr   is the maximum number of instruments,
  372.      MaxPatt  is the maximum number of patterns,
  373.      PattLen  is the maximum number of lines per pattern,
  374.      SongLen  is the maximum number of positions in a song,
  375.      InstrLen is the maximum size of an instrument in bytes,
  376.      Tracks   is the maximum number of tracks.
  377.  
  378.    Effects are the hardest thing to convert.  While Speed and Volume
  379. are almost the same between different music editors, some effects (such
  380. as Oktalyzer's H and L) cannot be converted because there are no
  381. equivalents in other music editors.  Therefore, you will have to modify
  382. the score manually if you intend to convert a module while keeping such
  383. effects.  In addition, some effects behave in different ways even if
  384. they claim to do the same thing.
  385.  
  386.    Last but not least, some music editors support synthetic or hybrid
  387. instruments.  XModule does not convert such instruments, because I can
  388. hardly think of a way to implement a sample to synth conversion (any
  389. ideas?). I used to like synthetic music, but it seems that all those
  390. great composers on the good old C64 have vanished...  Why have you
  391. musicians become so lazy? 8-(
  392.  
  393. NoiseTracker
  394. ============
  395.  
  396.    Noise/ProTracker 31 instruments module.  This is absolutely the most
  397. common module format; almost any music editor and module player (even
  398. the crap ones for the PeeCee) understand this format.  Noise/ProTracker
  399. modules can be recognized by looking for the ID M.K. at offset 1080
  400. ($438 in hex) in the file.  M.K. are the initials of Mahoney &
  401. Kaktus, the two guys who designed this format.
  402.  
  403.    Unfortunately, there is an infinite variety of standard NoiseTracker
  404. modules with fancy IDs. In fact, most tracker clones put their own ID
  405. instead of the standard one even if there is no reason to do it.  If
  406. you find such a module, try replacing the ID with an hex editor and you
  407. will be able to load it most of the times.
  408.  
  409. ProTracker 100 Patterns
  410. =======================
  411.  
  412.    XModule will automatically switch to ProTracker 100 whenever the
  413. module being saved exceeds the 64 patterns limit of NoiseTracker
  414. modules.  Modules with more than 64 patterns have the ID M!K! instead
  415. of the standard Noise/ProTracker ID (M.K.).
  416.  
  417.        Note: You must load such a module with ProTracker 2.3 or
  418. better in order to play/edit it.  Older players will either refuse to
  419. load it or they'll turn the module into scratch dance.
  420.  
  421.    ProTracker 3.0 has a completely new file format, but this isn't
  422. supported yet, as I've never seen a module of this kind yet.
  423.  
  424. SoundTracker 15 Instruments
  425. ===========================
  426.  
  427.    This format is pretty useless as SoundTracker is becoming really
  428. rare.  Do not save SoundTracker modules unless you really need to,
  429. because most players/editors will stop supporting this format very soon.
  430. There is no way to identify a SoundTracker module, therefore XModule
  431. will ask you to confirm a SoundTracker module when the file being
  432. loaded matches no other known module format.
  433.  
  434. StarTrekker
  435. ===========
  436.  
  437.    StarTrekker is another NoiseTracker clone, which is capable of
  438. playing modules with 4 or 8 channels and supports MIDI devices.  The
  439. format of 4 channels modules is the same of NoiseTracker, except for
  440. the FLT4 ID.  Modules with 8 channels have the ID FLT8, and keep
  441. the extra data in a second file, whose structure I don't know.  If you
  442. want support for 8 channels StarTrekker modules, please send me some
  443. information on its format.
  444.  
  445. UNIC-Tracker
  446. ============
  447.  
  448.    Actually, I've never seen UnicTracker, but I sometimes ripp Unic
  449. modules with ExoticRipper, so I decided to give support for this weird
  450. Tracker clone too.  The format is very similar to that of ProTracker
  451. modules, except for the EMW3 ID.
  452.  
  453. FastTracker
  454. ===========
  455.  
  456.    These modules are Standard Noise/ProTracker modules except that they
  457. have 6 or 8 tracks.  This format comes from a damn PeeCee tracker,
  458. which I've never seen.  Anyway, adding this format was a matter of five
  459. minutes.  XModule does not suppor FastTracker 2.0 modules (those with
  460. extension .xm) yet.
  461.  
  462. Oktalyzer 1.1
  463. =============
  464.  
  465.    Oktalyzer is an old editor which can play up to 8 channels by mixing
  466. instruments in real time.  Oktalyzer modules start with the ID
  467. OCTASONGGMOD.  Development of Oktalyzer has been discontinued, as
  468. the author seems to be programming on Windoze now.  It's really a
  469. shame, as many musicians found that Oktalyzer was one of the most
  470. powerful trackers for the Amiga.
  471.  
  472. MED
  473. ===
  474.  
  475.    Not all features of MED are supported by XModule.  In particular,
  476. synthetic and hybrid instruments are ignored.
  477.  
  478. OctaMED
  479. =======
  480.  
  481. ScreamTracker
  482. =============
  483.  
  484.    ScreamTracker 3.01 is a damn PeeCee program made by those Future Crew
  485. guys who are trying to turn clones into Amigas.  ScreamTracker has the
  486. amazing feature of playing 32 tracks, 16 of which are for 8 bit digital
  487. samples.  The other 16 tracks play ADLib FM synths (not supported by
  488. XModule.
  489.  
  490. MIDI File
  491. =========
  492.  
  493.    MIDI is the industry standard musical score format (the same way
  494. Windoze is the industry standard graphic interface :-).  The MIDI
  495. concept is very different from tracker modules.  There are no sequence
  496. and patterns, but a long stream of events (notes) that have to be sent
  497. to some musical device after a specific amount of time is elapsed.
  498. There are no instruments.  Instead, each note is associated with a
  499. preset number that matches a particular instrument.
  500.  
  501.    XModule's MIDI file saver is based on Andrew Scott's MidiMod program.
  502.  
  503. Optimization
  504. ************
  505.  
  506.    Module optimization is achieved by removing all unused data in such
  507. a way that the module will sound the same as before.  XModule can
  508. process a module to reduce its size as much as possible.  It is
  509. generally a good idea to optimize a module before distributing it, but
  510. never while you are still composing it, because you could easily loose
  511. some data that you didn't want to discard.  Do not expect to gain a lot
  512. of bytes optimizing modules: saving 20% of the total size is usually a
  513. very good result.
  514.  
  515. * Unused patterns
  516.      Some formats (e.g.: Sound/Noise/ProTracker) store empty patterns
  517.      in a module if a pattern with a greater number is used.  For
  518.      instance, a song using patterns 1, 2 and 5 will contain patterns 3
  519.      and 4 as well.
  520.  
  521.          Warning: If a song contains a part that has not been finished
  522.      yet and has not already been inserted in the position table, you
  523.      will lose it.
  524.  
  525.          Warning: When a song is saved to Noise/ProTracker, patterns
  526.      beyond the last used patterns are discarded regardless of this
  527.      switch.  This is due to a limitation of Noise/ProTracker module
  528.      format.
  529.  
  530. * Pattern Cutting
  531.      When a pattern is breaked with the Pattern Break effect, it is cut
  532.      to the line containing the break.  When saving to a format that
  533.      does not support variable length patterns (eg.: SoundTracker), the
  534.      pattern is grown again, so this optimization won't help with such
  535.      formats.
  536.  
  537. * Unused instruments
  538.      A composer may decide to use an instrument and then change his
  539.      mind, but forget to clear the instrument.  In this case the module
  540.      will contain an instrument that is never played.  These instruments
  541.      are simply stripped away.
  542.  
  543. * Sample data after a loop
  544.      The part of an instrument following a loop is never played and is
  545.      therefore discarded.
  546.  
  547. * Instruments zero tails
  548.      Long zero tails eat up memory and produce no sound.  This
  549.      optimization is performed only on loopless instruments, as a zero
  550.      sequence inside a loop does make difference.  XModule leaves at
  551.      least two zero bytes to avoid the nasty click produced by the
  552.      speaker dropping its volume to zero too quickly.
  553.  
  554. ARexx Interface
  555. ***************
  556.  
  557.    Sorry, sorry!  XModule's documentation is still incomplete.  The
  558. next release will hopefully be more accurate (it's already three
  559. releases I'm promising it :-).
  560.  
  561.    Anyway, XModule's ARexx port is a little brain dead at the moment,
  562. so you're not missing a great deal.
  563.  
  564. Known Bugs
  565. **********
  566.  
  567.    Murphy's laws state that nothing can be perfect, not even computer
  568. programs.  XModule is far from being perfect and I need your help to
  569. fix as many bugs as possible.  If you discover a bug which isn't
  570. reported in the list below (note: there is no list at the moment; this
  571. is a beta release, remember?), please notify me.
  572.  
  573.    When you report a bug, state exactly what happens and indicate how
  574. to reproduce the conditions that generated the problem.  Reports like
  575. `XModule sometimes crashes converting my favorite module' does not help
  576. at all.  Include your name if you want to be credited in future XModule
  577. releases.
  578.  
  579.    If the program refuses to convert a module, mail it to me on a disk
  580. or upload it to a BBS that I can reach and I'll try to fix the problem
  581. as soon as possible.  Glass Globe BBS, whose address can be found in
  582. the Author Info chapter, will do.  If you want the disk back with the
  583. fixed version of XModule, send me a self-addressed envelope with enough
  584. italian stamps or enough money for a reply.
  585.  
  586.    XModule has been tested on several machines running Kickstart 2.0,
  587. 3.0 and 3.1.  It should work on any 68K family processor (was tested on
  588. 68000, 68020 and 68040) and is Enforcer and Mungwall proof.  I also
  589. tested XModule with virtual memory programs such as VMM40 and found that
  590. everything seems to work correctly.
  591.  
  592. Future plans
  593. ************
  594.  
  595. * TeX
  596.      Another format I'd like to add is AmigaTeX.  If you know TeX,
  597.      you'll surely be wondering what a typesetting program can be used
  598.      for in music.  Well, AmigaTeX is at the moment is the best
  599.      implementation available on any computer of the TeX typesetting
  600.      environment, and its distribution includes MusicTeX, a powerful
  601.      music language which can output notes in a great standard staff
  602.      notation.  I know no other program on the Amiga that can print
  603.      notes of such fine quality (if you do, let me know!), so I think
  604.      that many musicians would appreciate such an option.
  605.  
  606. * Other module formats
  607.      Some formats I'd like to give support for in XModule as soon as
  608.      possible:
  609.  
  610.         - FastTracker II (.XM)
  611.  
  612.         - ScreamTracker (.S3M)
  613.  
  614.         - MultiTracker (.MTM)
  615.  
  616.         - OctaMED MMD1 and MMD2
  617.  
  618.         - Face The Music (.FTM)
  619.  
  620.         - Quadra Composer
  621.  
  622.      If you have documentation regarding a format you would like to see
  623.      in the next release, please send it to me together with a couple
  624.      of modules and, if possible and legal, the program that created
  625.      them.  I'll try to implement the new format only if it is somewhat
  626.      easy: it is very hard to convert, say, Future Composer to
  627.      SoundTracker.  Please, do not send a module without at least a
  628.      text file describing its structure, as I'm not willing to spend my
  629.      nights hex-dumping modules :-).
  630.  
  631. * External Loaders/Savers
  632.      Add support for 3rd party loaders and savers in XModule.
  633.      Currently, I'm thinking about the best implementation of the
  634.      external module interface.
  635.  
  636. * Full Module Editor
  637.      I'd like to turn XModule into a fully featured editing environment
  638.      for any kind of module, but this would require an enormous amount
  639.      of effort, and time is never enough...
  640.  
  641. Programmer notes
  642. ****************
  643.  
  644.    XModule has been written in C and compiled with SAS C 6.51, Other
  645. compilers may require some changes in the source code.
  646.  
  647.    The program is written in respect of the Amiga multitasking
  648. operative system and complies with Commodore programming guidelines.
  649. All allocated resources will be (hopefully) freed before program
  650. termination.  I wrote XModule with the goal in mind of keeping the
  651. executable fast and small.
  652.  
  653.    This manual has been typeset using MakeInfo, a GNU PD utility ported
  654. to the Amiga by Reinhard Spisser and Sebastiano Vigna.  I found that
  655. the time I saved writing one file for three was nearly compensated by
  656. the time spent learning how to operate MakeInfo.
  657.  
  658.    Besides, English is not my first language (as you might have
  659. guessed) and I bet this document is full of grammar mistakes.
  660.  
  661.    If you intend to translate, improve or somewhat edit this document,
  662. please work on the supplied TexInfo file and then process it with the
  663. utilities supplied in the MakeGuide distribution.  You can find
  664. MakeGuide in several PD libraries such as Aminet.
  665.  
  666.    Do not hesitate sending criticisms to my work, and, even better,
  667. advices on how to improve the program and its documentation.  See
  668. Author Info.
  669.  
  670. XModule Module Format
  671. *********************
  672.  
  673.    Before going into the details of the XModule module format, I'd like
  674. to explain why I felt the need to invent yet another module format.
  675. There were plenty of them, but none had the flexibility I was looking
  676. for. The only one exception is in my opinion OctaMED's MMD.  But the
  677. MMD file format is very complicated, hard to read and poorly
  678. documented.  When I designed it, I wanted XMOD to be as flexible, easy,
  679. efficient and expandable as possible.  If you are developing a music
  680. program, please consider supporting XMOD.  If you have troubles with
  681. the following format description, contact me and I'll be glad to help
  682. you.
  683.  
  684.    XModule modules are standard IFF files.  They consist of a sequence
  685. of chunks (also called proprieties) each storing a particular type of
  686. information related to the module.  Text chunks, such as NAME and AUTH
  687. chunks are variable sized and NOT null terminated.  When you read such
  688. a chunk, you should take care to clip the string to your maximum buffer
  689. size.  NAME and AUTH fields are optional and should be assumed empty
  690. when missing.
  691.  
  692.    As with every IFF file, you should not depend on the order and size
  693. of any chunk.  However, as usual with most IFF formats, header chunks
  694. must always precede related BODY chunks.  XModule requires this for
  695. PHDR chunks because it isn't possible to load a pattern without knowing
  696. its length and number of tracks.  Some chunks may grow in size in
  697. future versions of XModule.
  698.  
  699.      FORM XMOD
  700.      
  701.        [NAME]
  702.          The name chunk contains the original name used to save the module.
  703.      
  704.        [ANNO]
  705.          XModule stores its copyright information here.
  706.      
  707.        MHDR
  708.          Module header.  Contains a ModuleHeader structure as defined in
  709.          <XModuleClass.h>.
  710.      
  711.        FORM SONG
  712.          The song FORM contains all data relative to one song.  Any
  713.          number of songs can be stored into one module.
  714.      
  715.          [NAME]
  716.            Name of the song.
  717.      
  718.          [AUTH]
  719.            Author of the song.
  720.      
  721.          SHDR
  722.            Song Header.  Contains a SongHeader structure as defined in
  723.            <XModuleClass.h>.
  724.      
  725.          SEQN
  726.            Song Sequence.  The contents of this chunk are unsigned bytes
  727.            representing the pattern to play at a particular position.
  728.            The size of this chunk should match the Length field of the
  729.            SongHeader.
  730.            When a song contains multiple sections, one SEQN chunk will
  731.            be stored for each section (not implemented).
  732.      
  733.          FORM PATT
  734.            Each occurrence of this FORM contains one pattern.  Patterns
  735.            are numbered starting from 0.  Each pattern has its own
  736.            length and number of tracks.
  737.      
  738.            [NAME]
  739.              Name of this Pattern.
  740.      
  741.            PHDR
  742.              Pattern Header.  Contains a PatternHeader structure as
  743.              defined in <XModuleClass.h>.
  744.      
  745.            BODY
  746.              The BODY chunk is stored as an array of PatternNote
  747.              structures.  Tracks are stored one after the other.
  748.              There are NumTracks*Length Note structures in the BODY
  749.              chunk.
  750.      
  751.          END FORM PATT
  752.      
  753.          FORM 8SVX
  754.            Each SONG contains one or more occurences of this FORM,
  755.            one for each sample.  XModule currently saves and loads
  756.            only the NAME, VHDR and BODY chunks.  Be prepared to
  757.            decode Fibonacci Delta Encoded BODY chunks. An
  758.            additional non-standard chunk is saved:
  759.      
  760.            INST
  761.              XModule instrument info.  Contains an InstrumentInfo
  762.              structure  as defined in <XModuleClass.h>.
  763.      
  764.            When the BODY chunk is missing, the sample must be
  765.            loaded from the instrument library using the contents
  766.            of the NAME chunk as the file name.
  767.      
  768.            See the IFF 8SVX documentation for more details.
  769.      
  770.          END FORM 8SVX
  771.      
  772.        END FORM SONG
  773.      
  774.      END FORM XMOD
  775.  
  776. Credits
  777. *******
  778.  
  779.    * Alastair Booker, for suggestions and help with the FastTracker
  780.      format.
  781.  
  782.      It is not your fault if Intel systems are so unstable! :-)))
  783.  
  784.    * Fabio Barzagli, for beta testing XModule and for giving me all his
  785.      awesome modules!
  786.  
  787.      Keep on making good music, Fabio!
  788.  
  789.    * Massimo Brogioni, for being my boss and for spreading all those
  790.      bogus XModule releases all around the world.
  791.  
  792.      Hey boss, have you got a spare 5Gig hard disk?
  793.  
  794.    * Alessandro Lombardi, for 2.x beta testing.
  795.  
  796.      Stop deleting files!
  797.  
  798.    * Erno Tuomainen, for his wonderful finnish BBS, for his kindness
  799.      and for all the support he gave me.
  800.  
  801.      Are there any more top-rated modules to leech?
  802.  
  803.    * Pauli Porkka, for his kindness, for letting me win a free DASMP
  804.      key, for the sources and for all the e-mails.
  805.  
  806.      Will you support my format in the next DASMP release?
  807.  
  808.    * Woody (Nicola Ferruzzi), for S3M and XM format descriptions.
  809.  
  810.      I'll send you a postcard from Japan as soon as I go there. :-)
  811.  
  812.    * The Amiga, for being the best computer in the world. :^)
  813.  
  814.      Commodore: You've put really a lot of efford trying to kill the
  815.      Amiga, but you won't succeed!
  816.  
  817. How to contact the author
  818. *************************
  819.  
  820.    If you want to make me aware of your suggestions, bug reports, ideas
  821. or you want to send me a gift, a good module or, why not, some money
  822. :-), reach me in any of the following ways:
  823.  
  824. * Mail
  825.           Bernardo Innocenti
  826.           Via Ventiquattro Maggio, 14
  827.           50129 - Firenze
  828.           ITALY
  829.  
  830. * FAX
  831.           +39-55-8877771
  832.           Attn:  Bernardo Innocenti
  833.           Subj:  Amiga/XModule
  834.  
  835. * E-Mail
  836.           FidoNet:  Bernardo Innocenti 2:332/118.4
  837.           AmigaNet: Bernardo Innocenti 39:102/201.4
  838.           UseNet:   bernie@shock.nervous.com
  839.  
  840.    I will try to reply to all my E-Mail, but I'm too lazy to reply
  841. old-style mail.  Your suggestions will be taken into account unless
  842. they are `I want XModule to do ice tea'-style.
  843.  
  844. Concept Index
  845. *************
  846.  
  847.  
  848.  
  849.  100 Patterns ProTracker modules        ProTracker
  850.  6CHN                                   FastTracker
  851.  8CHN                                   FastTracker
  852.  Acknowledgements                       Credits
  853.  Arguments, command line                Getting Started
  854.  Author's address                       Author Info
  855.  Break signals                          Commodities
  856.  Bug reports                            Known Bugs
  857.  Bugs, known ones                       Known Bugs
  858.  Compiling XModule                      Programmers
  859.  Contact the author, how to             Author Info
  860.  Credits                                Credits
  861.  def_Instrument                         Default Icons
  862.  def_Module                             Default Icons
  863.  Distribution                           Distribution
  864.  File Format used by XModule            XModule Format
  865.  Font Sensivity                         Windows Layout
  866.  GUI                                    User Interface
  867.  Help, On-Line                          On-Line Help
  868.  How to contact the author              Author Info
  869.  Icons, changing defaults               Default Icons
  870.  Keys, Shortcuts                        Shortcut Keys
  871.  Known Bugs                             Known Bugs
  872.  Language selection                     Localization
  873.  Layout, of Windows                     Windows Layout
  874.  Localization                           Localization
  875.  M!K!                                   ProTracker
  876.  MED                                    MED
  877.  MIDI File                              MIDI File
  878.  MMD Format                             MED
  879.  Modifying XModule                      Programmers
  880.  NoiseTracker                           NoiseTracker
  881.  OctaMED                                OctaMED
  882.  Oktalyzer                              Oktalyzer
  883.  On-Line Help                           On-Line Help
  884.  Optimization                           Optimization
  885.  Overview of XModule                    Overview
  886.  Panels                                 Panels
  887.  Programmers, notes for                 Programmers
  888.  ProTracker                             ProTracker
  889.  S3M Format                             ScreamTracker
  890.  ScreamTracker                          ScreamTracker
  891.  Shortcut Keys                          Shortcut Keys
  892.  SoundTracker                           SoundTracker
  893.  Starting XModule                       Getting Started
  894.  StarTrekker                            StarTrekker
  895.  Thanks                                 Credits
  896.  ToolTypes                              Getting Started
  897.  UNIC-Tracker                           UNIC-Tracker
  898.  Usage                                  Getting Started
  899.  User Interface                         User Interface
  900.  Windows                                Panels
  901.  Windows Layout                         Windows Layout
  902.  XModule overview                       Overview
  903.  
  904.